超长文档的 AI 生成策略：ralph-loop 分段生成
你会学到什么
前面几节我们讲了单个文档的生成——一份需求文档、一个PPT、一份Word报告。但实际工作中经常遇到"超长文档"：30页的产品需求文档、50页的技术方案、100页的培训教材。
这类文档用 AI 一次性生成会出问题：后面内容质量下降、风格不一致、容易遇到 token 限制。传统做法是手动分段复制粘贴，费时费力且风格容易割裂。
本节介绍 /ralph-loop 技能——一种循环执行任务的自动化方案，让 AI 逐章迭代生成超长文档，每段都保持一致风格，直到完成。
超长文档的生成困境
什么算"超长文档"
| 文档类型 | 页数 | AI 一次性生成 |
|---|---|---|
| 短文档 | 1-5 页 | ✅ 没问题 |
| 中文档 | 5-15 页 | ⚠️ 质量开始下降 |
| 长文档 | 15-30 页 | ❌ 风格不一致 |
| 超长文档 | 30+ 页 | ❌❌ token 限制 + 质量崩塌 |
核心问题：AI 生成内容时，上下文窗口有限制（当前主流模型 100k-200k token）。生成 30 页文档时，后面的内容可能"忘记"了前面的风格和结构要求。
传统方案的问题
方案一：一次性生成
请帮我生成一份完整的30页产品需求文档，包含以下章节...
markdown
问题：
- 后面章节质量明显下降（AI 注意力分散）
- 风格不一致（前3章用"我们"，第4章突然用"系统"）
- 容易触达 token 上限（生成一半就断了）
方案二：手动分段
手动把需求拆成 5 份，每次让 AI 生成一个章节：
第一轮：请生成第一章——产品背景
第二轮：请生成第二章——用户分析
第三轮：请生成第三章——功能需求
...
markdown
问题：
- 手动复制粘贴拼接（耗时）
- 风格容易割裂（每次 AI 重新理解风格）
- 需要人工监督每轮生成
方案三：多 Agent 并行
让多个 AI Agent 同时生成不同章节，最后合并。
问题：
- 风格不统一（每个 Agent 有自己的写作习惯）
- 章节衔接生硬（缺乏整体连贯性）
- 配置复杂（需要设计 Agent 通信协议）
ralph-loop：循环生成的解决方案
核心思路
ralph-loop 的核心是**"相同 prompt，重复执行，看到上次的工作"**：
while true; do
AI 收到相同的 prompt
↓
AI 看到上一次生成的文件（已经存在）
↓
AI 继续写下一章
↓
尝试退出时，Hook 拦截，重新注入 prompt
↓
循环直到完成（检测到 <promise> 标签）
text
关键点：AI 不是"看到自己的输出"，而是"看到文件系统中已经存在的内容"。这保证了每轮生成时，AI 知道前面写了什么。
与普通 /loop 的区别
| 特性 | ralph-loop | 普通 /loop |
|---|---|---|
| 触发方式 | /ralph-loop "prompt" | /loop 10m command |
| 执行模式 | 会话内循环执行 | 定时执行命令 |
| 上下文 | 看到之前的文件修改 | 无上下文关联 |
| 结束条件 | <promise> 标签或 --max-iterations | 手动取消 |
| 适用场景 | 迭代式任务（文档生成、重构） | 定时轮询（状态检查） |
前置条件：前几节创建的 Skills
ralph-loop 本身只是"循环框架"，实际生成文档需要配合前面章节中创建或安装的 Skills：
| 生成目标 | 配合 Skill | 来源 | 作用 |
|---|---|---|---|
| Word 文档 | /docx | 第6章01节（内置） | Markdown 转 Word，支持标题/表格/目录 |
| 中文 Word 文档（去AI化） | /cn-docx | 第6章01节（手动安装） | 符合国标 GB/T 8567-2006 + 消除AI痕迹 |
| PPT 演示文稿 | frontend-slides / skywork-ppt | 第6章03节 | HTML 幻灯片 或 原生 PPTX 生成 |
| 技术方案 | /doc-coauthoring | 第6章01节（内置） | 协作式迭代写作，三步工作流 |
| 信息搜索 | local-search | 第5章02节（手动创建） | 搜索 → 爬取 → 整理，补充实时数据 |
| Markdown 文档 | 无需额外 Skill | — | Claude Code 原生支持 |
回顾安装方式（详见对应章节）：
/docx、/doc-coauthoring：Claude Code 内置，直接使用/cn-docx：手动创建~/.claude/skills/cn-docx/SKILL.md（第6章01节有完整步骤）local-search：手动创建~/.claude/skills/local-search/SKILL.md+ 配置 MCP 服务器（第5章02节有完整步骤）frontend-slides/skywork-ppt：通过 Skill 市场或手动安装（第6章03节）
超长文档生成的完整工作流
第一步：准备大纲
在项目根目录创建 outline.md 或写入 CLAUDE.md：
## 文档大纲
# 产品需求文档：智能客服系统
## 第一章：产品背景
- 行业现状
- 痛点分析
- 解决方案概述
## 第二章：用户分析
- 目标用户
- 用户画像
- 使用场景
## 第三章：功能需求
- 核心功能
- 扩展功能
- 未来规划
## 第四章：技术架构
- 系统架构图
- 技术选型
- 数据设计
## 第五章：项目计划
- 开发排期
- 里程碑
- 风险评估
markdown
第二步：配置 ralph-loop
/ralph-loop "根据 outline.md 继续生成产品需求文档的下一章，每章生成独立的 .md 文件，生成到第五章完成后输出 <promise>DOC_COMPLETE</promise>" --max-iterations 10
bash
参数说明：
--max-iterations 10：最多循环 10 次（防止无限循环）<promise>DOC_COMPLETE</promise>：完成信号，检测到此标签后自动停止
第三步：逐章生成 + 质量检查
ralph-loop 启动后，每轮会：
- 读取已生成的文件（知道进度）
- 生成下一章内容
- 保存到对应文件
- 尝试退出时被 Hook 拦截
- 重新注入相同 prompt
- 继续下一轮
人工介入：如果某章生成不理想，可以直接编辑文件，下一轮 ralph-loop 会看到你的修改。
第四步：合并 + 统一样式
所有章节生成完成后，使用 Python 脚本合并：
from pathlib import Path
# 按顺序读取章节
chapters = [
"01-产品背景.md",
"02-用户分析.md",
"03-功能需求.md",
"04-技术架构.md",
"05-项目计划.md"
]
output = Path("产品需求文档-完整版.md")
with open(output, "w", encoding="utf-8") as f:
for chapter in chapters:
chapter_file = Path(chapter)
if chapter_file.exists():
content = chapter_file.read_text(encoding="utf-8")
f.write(f"\n\n# {chapter_file.stem}\n\n")
f.write(content)
f.write("\n\n---\n\n")
print(f"合并完成：{output}")
python
实战案例：生成 30 页产品需求文档
场景描述
需要生成一份完整的"智能客服系统产品需求文档"，包含 5 个章节，预计 30+ 页。
大纲准备
创建 docs/outline.md：
# 智能客服系统 PRD 大纲
## 产品背景.md
- 行业现状（客服行业市场规模、痛点）
- 竞品分析（3家主流产品对比表）
- 解决方案概述（AI+人工混合模式）
## 用户分析.md
- 目标用户（企业客户、最终用户、客服人员）
- 用户画像（3个典型用户故事）
- 使用场景（5个高频场景流程图）
## 功能需求.md
- 核心功能（智能问答、工单系统、知识库）
- 扩展功能（多渠道接入、数据分析）
- 功能优先级矩阵（MoSCoW 分析）
## 技术架构.md
- 系统架构图（Mermaid 流程图）
- 技术选型（后端/前端/AI 模型）
- 数据设计（ER 图）
## 项目计划.md
- 开发排期（甘特图）
- 里程碑（6个关键节点）
- 风险评估（风险矩阵表）
markdown
ralph-loop 配置
/ralph-loop "根据 docs/outline.md 继续生成 PRD 的下一章。要求：
1. 每章生成独立的 .md 文件到 docs/ 目录
2. 使用 Mermaid 画图（流程图、ER图）
3. 表格用 Markdown 表格语法
4. 保持一致的风格：专业、简洁、数据驱动
5. 生成完第五章后，输出 <promise>PRD_COMPLETE</promise>" --max-iterations 8
bash
生成过程示例
第一轮：AI 读取 outline.md，生成 01-产品背景.md
# 产品背景
## 行业现状
根据艾瑞咨询 2025 年报告，中国客服市场规模达到 380 亿元...
## 竞品分析
| 产品 | 价格 | 优势 | 劣势 |
|-----|------|-----|------|
| 产品A | ... | ... | ... |
markdown
第二轮：AI 看到已生成的 01-产品背景.md，生成 02-用户分析.md，风格自动保持一致
第三轮：AI 继续生成 03-功能需求.md
...
第五轮：AI 生成 05-项目计划.md，检测到已完成所有章节，输出 <promise>PRD_COMPLETE</promise>，ralph-loop 自动停止
合并最终文档
merge_prd.py
python
生成 智能客服系统PRD-完整版.md，用 slidev-generator 转换为 PPT，或用 docx Skill 转换为 Word。
最佳实践和避坑指南
每轮生成的最优长度
| 文档类型 | 建议每轮长度 | 原因 |
|---|---|---|
| 技术文档 | 2000-3000 字 | 保持信息密度，避免 AI 注水 |
| PPT | 5-8 页 | 保持视觉一致性 |
| Word 文档 | 3-5 页 | 方便审查和修改 |
过短（<1000 字）：频繁切换上下文，风格容易飘
过长（>5000 字）：单轮质量下降，失去分段意义
保持风格一致性的技巧
1. 在 CLAUDE.md 中固定风格规则
## 文档风格
所有生成的文档遵循以下规则：
- 标题层级：最多三级（## / ### / ####）
- 列表：用 `- ` 而非 `1. `（除非需要编号）
- 表格：必须有表头
- 代码块：指定语言（\```python 而非 \```）
- 无 emoji（除非是用户明确要求的演讲稿）
markdown
2. 使用模板文件
创建 docs/template.md：
# {章节标题}
## 背景
{背景内容}
## 分析
{分析内容}
## 总结
{总结内容}
markdown
prompt 中要求 AI 遵循模板结构。
错误恢复策略
| 错误场景 | 恢复方法 |
|---|---|
| 某章生成不完整 | 手动编辑该文件补充，ralph-loop 下一轮会看到修改 |
| 风格突然变化 | 在 CLAUDE.md 中强化风格约束，重新启动 ralph-loop |
| 生成到一半中断 | 检查已生成的文件，用 /cancel-ralph 取消后重新启动 |
| 无限循环 | 用 --max-iterations 限制最大次数，或 /cancel-ralph 手动取消 |
ralph-loop 使用检查清单
启动前确认：
- 大纲文件已准备好（outline.md 或 CLAUDE.md）
- 完成信号已定义（
<promise>XXX</promise>） - 最大迭代次数已设置（
--max-iterations） - 输出目录已存在（docs/ 或 output/）
- 相关 Skills 已安装（docx / slidev-generator）
运行中监控：
- 每轮生成后检查文件内容
- 发现问题时及时手动修正
- 注意轮次是否接近
--max-iterations上限
完成后验证：
- 所有章节都已生成
- 文件可以正常合并
- 转换为目标格式（PPT/Word）无报错
本节要点
- 超长文档（30+ 页）不能一次性生成：质量下降、风格不一致、token 限制
- 传统分段方案问题：手动拼接耗时、风格割裂、需要人工监督
- ralph-loop 的核心价值：相同 prompt 循环执行，AI 看到之前的工作，自动迭代直到完成
- 工作流四步骤：准备大纲 → 配置 ralph-loop → 逐章生成 → 合并统一样式
- 关键技巧：在 CLAUDE.md 中固定风格、使用模板文件、设置合理的
--max-iterations
总结表格
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 一次性生成 | 5 页以内短文档 | 快速、简单 | 超长文档质量崩塌 |
| 手动分段 | 偶尔需要长文档 | 灵活、可控 | 耗时、风格割裂 |
| 多 Agent 并行 | 时间紧迫的项目 | 并行生成速度快 | 风格难统一、配置复杂 |
| ralph-loop | 超长文档（30+ 页） | 自动化、风格一致、可迭代 | 需要配置 prompt 和结束条件 |
一句话原则：超长文档用 ralph-loop 循环生成，每轮看到之前的工作，保持风格一致，直到检测到完成信号自动停止。
↑